An append-only log on IPFS.
ipfs-log is a partially ordered linked list of IPFS objects.
This module provides a data-agnostic transport mechanism using IPFS with the ability to traverse the history. Every entry in the log is saved in IPFS and each points to a hash of previous entry(ies). Logs can be forked and joined back together.
entry0 <-- entry1 <-- entry2 ...
The module works in Node.js and Browsers.
IPFS Log has a few use cases:
It was originally created for, and currently used in, orbit-db - a distributed peer-to-peer database on IPFS.
npm install ipfs-log
See examples for more details.
Install dependencies:
npm install ipfs-log ipfs
Run a simple program:
const IPFS = require('ipfs')
const Log = require('ipfs-log')
const ipfs = new IPFS()
const log = new Log(ipfs, 'A')
log.add({ some: 'data' })
.then(() => log.add('text'))
.then(() => console.log(log.items))
// [
// {
// payload: { some: 'data' },
// hash: 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD',
// next: []
// },
// {
// payload: 'text',
// hash: 'QmdNFpoyXLNdR8Wx5LYZBLcXH8aAEopSMnnubWLn4AciCZ',
// next: [ 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD' ]
// }
// ]
See examples for details.
node examples/log.js
const IPFS = require('ipfs')
const Log = require('ipfs-log')
const log = new Log(new IPFS(), 'A', { maxHistory: 1000 })
log.add('one')
.then((entry1) => {
console.log('Entry1:', entry1.hash, entry1.payload)
return log.add('two')
})
.then((entry2) => {
console.log('Entry2:', entry2.hash, entry2.payload)
console.log('Entry2.next:', entry2.next[0]) // == entry1.hash
})
The distribution package for browsers is located in dist/ipfslog.min.js
See examples/browser for details.
Open examples/browser/index.html or examples/browser/browser.html in your browser.
<html>
<head>
<meta charset="utf-8">
</head>
<body>
<script type="text/javascript" src="../../dist/ipfslog.min.js" charset="utf-8"></script>
<script type="text/javascript" src="../../node_modules/ipfs/dist/index.js" charset="utf-8"></script>
<script type="text/javascript">
const ipfs = new window.Ipfs()
const log = new Log(ipfs, 'A')
log.add('one')
.then((entry1) => {
console.log('Entry1:', entry1.hash, entry1.payload, entry1)
return log.add('two')
})
.then((entry2) => {
console.log('Entry2:', entry2.hash, entry2.payload, entry2)
console.log("Entry2.next:", entry2.next[0])
});
</script>
</body>
</html>
npm install
npm run build
const Log = require('ipfs-log')
Create a log. The first argument is an ipfs instance which can be of type js-ipfs or js-ipfs-api. See https://github.com/ipfs/js-ipfs-api for IPFS api documentation.
const ipfs = require('ipfs')() // ipfs javascript implementation
// Or
const ipfs = require('ipfs-api')() // local ipfs daemon (go-ipfs)
const log = new Log(ipfs, 'logid') // 'logid' is a unique identifier for the log, this can usually be a user id
ipfs is an instance of IPFS (ipfs or ipfs-api)
id is a unique log identifier. Usually this should be a user id or similar.
options are the following:
{
maxHistory: 1000 // number of item to fetch at sync
}
Add a log entry. The new entry gets the references to previous entries automatically. Returns a Promise that resolves to the added Entry.
data can be any type of data: Number, String, Object, etc. It can also be an instance of Entry.
log.add({ some: 'data' })
.then(() => log.add('text'))
.then(() => console.log(log.items))
//[
// {
// payload: { some: 'data' },
// hash: 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD',
// next: []
// },
// {
// payload: 'text',
// hash: 'QmdNFpoyXLNdR8Wx5LYZBLcXH8aAEopSMnnubWLn4AciCZ',
// next: [ 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD' ]
// }
//]
Joins the log with other log. Fetches history up to options.maxHistory items, ie. items that are not in this log but referred to in items in other. Returns a Promise that resolves to an Array of items that were added.
// log1.items ==> ['A', 'B', 'C']
// log2.items ==> ['C', 'D', 'E']
log1.join(log2).then((added) => console.log(added)) // ==> ['D', 'E']
// log1.items ==> ['A', 'B', 'C', 'D', 'E']
Returns an Array of all items in the log.
const items = log.items;
// items ==> ['A', 'B', 'C']
Returns a snapshot of the log with items in the current batch. Current batch are the items in the log that have been added locally after the latest join with another log.
const snapshot = log.snapshot
// snapshot ==> { id: 'log id', items: ['A', 'B', 'C']}
All static methods take an ipfs instance as the first parameter. The ipfs can be of js-ipfs or js-ipfs-api. See https://github.com/ipfs/js-ipfs-api for IPFS api documentation.
const ipfs = require('ipfs')() // js-ipfs
// Or
const ipfs = require('ipfs-api')() // local ipfs daemon
See Instance methods on how to use the log instance
Get the IPFS hash of this log. Returns a Promise that resolves to an IPFS hash.
Log.getIpfsHash(ipfs, log).then((hash) => console.log(hash))
// ==> 'Qm...abc123'
Create a log from an IPFS hash. Returns a Promise that resolves to a Log instance.
Log.fromIpfsHash(ipfs, hash).then((log) => console.log(log))
// ==> instance of Log
npm install
npm test
The build script will build the distribution file for browsers.
npm run build
There's a simple benchmark program that can be used to compare performance between two version of ipfs-log. It measures write ops / second.
npm install
node examples/benchmark.js
This will output:
Starting benchmark...
131 queries per second, 131 queries in 1 seconds
50 queries per second, 181 queries in 2 seconds
44 queries per second, 225 queries in 3 seconds
84 queries per second, 309 queries in 4 seconds
111 queries per second, 420 queries in 5 seconds
142 queries per second, 562 queries in 6 seconds
157 queries per second, 719 queries in 7 seconds
195 queries per second, 914 queries in 8 seconds
171 queries per second, 1085 queries in 9 seconds
--> Average of 125 q/s in the last 10 seconds
...
PRs and issues are gladly accepted! Take a look at the open issues, too, to see if there is anything that you could do or someone else has already done. Here are some things I know I need:
MIT © 2016 Haadcode
FAQs
Append-only log CRDT on IPFS
The npm package ipfs-log receives a total of 459 weekly downloads. As such, ipfs-log popularity was classified as not popular.
We found that ipfs-log demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.